Please ensure Javascript is enabled for purposes of website accessibility
Powered by Zoomin Software. For more details please contactZoomin

AVEVA™ Asset Information Management

TABLE OF CONTENTS

Connect to an Aconex DMS

Save PDF
Save selected topicSave selected topic and subtopicsSave all topics
Share
Share to emailCopy topic URL
  • Last UpdatedApr 15, 2025
  • 11 minute read

The Aconex sample is a json split into six main sections. Some configuration parts of the sections are already hardcoded in the template so the sample includes only some of the configurations, as follows:

  • Authentication

  • DmsConfiguration

  • MetadataAIMContext

  • AIMIngestion

  • HttpSettings

  • PipelineRunnerSettings

Authentication

For Aconex, the Document Connector supports both Refresh Token Grant Type and Client Credentials Grant Type using Oracle Smart Construction Platform OAuth. The recommendation is to use the Client Credentials Grant Type for any existing or new Aconex connector configurations. For more information on how to get client credentials from Aconex, see the section below: "Getting Aconex Client Credentials from Oracle".

Refresh Token Grant Type (Legacy)

Aconex can use Oauth2 with the Authorization Code grant type, and for every code generation we will need human interaction. Once a combination of access and refresh tokens is generated, we can reuse the refresh token to generate new pairs of tokens, but only if the regeneration is done in less than two weeks. It is the responsibility of whoever is configuring the DMS to provide the Refresh Token along with the Data Pipeline parameters.

Note:

  • This method is now considered legacy and will be deprecated by Oracle soon.

  • It is recommended to migrate any existing Refresh Token Grant Type (legacy OAuth) integrations to Client Credential Grant type (Lobby OAuth) integrations. Support from Aconex for Refresh Token Grant Type authentication will only continue for existing implementations until 1st September 2024.

  • If you are still using the Refresh Token Grant Type (Legacy) authentication, then replace the Authentication section with the following:

    "Authentication": {

    "AuthenticationMethod": "Oauth2Refresh",

    "Oauth2RefreshAuthenticationDetails": {

    "AuthorizeApi": "https://sso-us1.aconex.com/as/token.oauth2",

    "BasicLogin": {

    "username": "",

    "password": ""

    },

    "RefreshTokenParameter": "RefreshTokenParameter"

    }

    }

This means that for Aconex we need to configure the Oauth2 Refresh grant type as follows:

  • BasicLogin

    • username: the Client ID provided by Aconex

    • password: the Client Secret provided by Aconex

  • RefreshTokenParameter

    Only for systems that use Oauth2 with Authorization Code grant type. A combination of access and refresh token should be manually generated and the refresh token should be passed here.

    On every run of the Add Source System pipeline, a RefreshToken is mandatory and should be valid.

    Note: Every time the on-boarding pipeline is run the Aconex Sample file must be updated with a new Refresh token

Client Credentials Grant Type (Recommended)

With the Client Credentials grant type, Aconex can support user-bound integration without requiring user interaction in order to request an access token. Each time the integration calls an Aconex API, the call will be made in the context of this user. The Aconex user account must be linked to a Lobby account. A single set of client credentials can be used for multiple Aconex connector configurations.

To configure OAuth2 with client credentials, configure the following values:

  • BasicLogin

    • username: the Client ID provided by Aconex.

    • password: the Client Secret provided by Aconex.

  • BodyRequestValues

    • user_id: Aconex user ID. The user ID of the linked Aconex account for the user. This does not need to be specified if there is only one Aconex account linked to the Lobby account.

    • user_site: Aconex user site. The URL of the Aconex instance on which the linked Aconex account is located. This does not need to be specified if there is only one Aconex account linked to the Lobby account.

      Note: Should user_id and user_site not be required, then neither parameter or value should exist in the request body.

The values for the other parameters are provided in the example.

If you are migrating from Refresh Token Grant Type (legacy) authentication to the recommended Client Credential Grant type (Lobby OAuth) authentication, then ensure you replace the authentication section with the following:

"Authentication": {

"AuthenticationMethod": "Oauth2",

"Oauth2AuthenticationDetails": {

"AuthorizeApi": "https://constructionandengineering.oraclecloud.com/auth/token",

"BasicLogin": {

"username": "",

"password": ""

},

"BodyRequestValues": {

"grant_type": "client_credentials",

"user_id": "",

"user_site": ""

}

}

}

DmsConfiguration

DmsConfiguration is a section where we configure DMS-related settings such as formats, endpoints, query parameters and so on.

  • DMSBaseUrl: represents the base url of the endpoints that will be used. It is the common part of all the URLs that will be consumed.

  • DeltaEndpoint: represents the endpoint that returns an expected list of documents that must be pushed to ingestion. Usually, this endpoint returns a Delta instead of all the documents. Delta represents all the documents that are new or were modified between a certain date and the actual moment. Usually that certain date is transmitted to the endpoint as a query parameter.

  • DeltaQueryParameters

    • search_query: Aconex enables us to configure detailed searches for documents. If we want to return the minimum information you require the documents IDs filtered by last modified date. Use the %DeltaDate% as a wildcard for the starting date.

    • return_fields: Aconex enables you to configure what metadata we need. So you can add a list of properties you want to be returned.

      For example, the return_fields can return the docNo (represents the DocumentNumber metadata in Aconex), if present. This will allow further mappings to be opened. For example: "return_fields": "registered,docNo".

    • search_type: The searching services provide the ability to perform different types of searches. One can perform a paged search which allows the user to request back a specific page from a large number of results.

    • page_size: This parameter is available only if search_type is explicitly set to PAGED. If specified, the value must be a number that is divisible by 25. Without this parameter specified, this defaults to 25.

      Note: This parameter has a maximum value of 500. If the number is not divisible by 25, it will return bad request.

  • Filtering

    • FilteringItem

      • Identifier: a unique identifier of the filteringItem; an identifier that will be used in the ValidationExpression.

      • Mapping: the actual filtering name.

      • Value: the actual value against which the filtering is done; it can contain a list of values separated by commas.

    • ValidationExpression: a filtering condition based on the identifiers already created and the logical operators in use OR and AND.

      Note: Supported filters are:
      RegisterDocument.Confidential|RegisterDocument.FileType|RegisterDocument.DocumentType
      These are not configurable.

      Filtering can be configured by adding the following section within the DmsConfiguration section. The example is shown with sample values which must be replaced with actual values before adding to your configuration.

      "Filtering": {

      "Filteringitems": [

      {

      "identifier": "sampleIdentifier",

      "mapping": "sampleMapping",

      "value": "sampleValue"

      },

      {

      "identifier": "testIdentifier",

      "mapping": "testMapping",

      "value": "testValue"

      }

      ],

      "ValidationExpression": "{sampleIdentifier} or {testIdentifier}"

      }

  • DeltaListOfResultsName: In order to configure this you must be aware of the looping requirements. Considering the response is a xml or jsn tree, you need to point which level is the repetitive one (point the documents level). To that you must specify every level with dots in between (lvl1.lvl2.lvl3).

  • MetadataFromDelta: boolean. Informs the program if the delta response includes the mandatory information, other than the document ID. In order to download a file you need more information about the file. You need the filename that contains the extension, and a title. Also, if possible you need the filesize but it is optional. If the delta response is not able to give us all the information we need to make another call in order to get document’s metadata.

  • DeltaMapping

    • id: Mapping for the document ID in the delta response. The mapping must be added surrounded by brackets. Mapping is similar to DeltaListOfResultsName but this time only for the document object. See the Sample Aconex Configuration File for a sample.

      If docNo is part of the DeltaQueryParameters.return_fields, then this can be used in DeltaMapping.id by using the documentNumber value. For example: "id": "{documentNumber}". This means that the manifest file generated will contain the value of the DocumentNumber for the DocumentIdentifier.

    • DocumentDownloadLink: URL used to download the document. Includes the document ID mapping as parameter added between brackets. See the Sample Aconex Configuration File for a sample.

    • MetadataDownloadLink: URL used to download the document metadata. It must contain the document ID mapping as parameter added between brackets. See the Sample Aconex Configuration File for a sample.

  • MetadataMapping

    • title: fixed string, mapping or combination. It will represent the pattern for document title. Mappings is done just as for the id and it must be surrounded by brackets. Mapping is related to delta response or to metadata response (MetadataDownloadLink) depending on MetadataFromDelta value.

    • filename: fixed string, mapping or combination. It will represent the pattern for document title. Mappings is done just as for the id and it must be surrounded by brackets. Mapping is related to delta response or to metadata response (MetadataDownloadLink) depending on MetadataFromDelta value.endpoint that returns the packages list.

    • filesize: optional. The mapping must be added surrounded by brackets. Mapping is similar to DeltaListOfResultsName but this time only for the document object. See the Sample Aconex Configuration File for a sample.

  • DeltaPaging

    • TotalPagesFromResult: The total number of pages available. Only applicable to a paged search.

    • QueryParameterPageNumber: This parameter is available only if search_type is explicitly set to PAGED. If specified, the value must be between 1 and the value of the TotalPages attribute that is in the response, otherwise an error is returned. Without this parameter specified, this defaults to 1.

  • IsMetadataToStore: boolean. Flag that let us save the response from MetadataDownloadLink as regi file or not.

  • DateTimeFormat: is a string representation of the date format supported by DMS when calling the DeltaEndpoint. Different DMSs may use different formats so we need to convert our date to the DMS format before starting any request that contains a date.

    Limitation: The DateTimeFormat for Aconex must be "yyyyMMdd". If this parameter value is not as mentioned, an empty delta will be returned, and no document will be processed.

MetadataAIMContext

MetadataAIMContext is a section where we configure what we send to the Ingestion API, such as paths, groups, naming formats, extensions and so on.

  • context: value sent to ingestion and used to group files for clients with multiple tenants

  • ClassLibraryRegisterPath

    • DocumentMetadataRegister: path for the document revisions.

    • ScrapedFileRegister: path for scraped files.

    • DocLinkAIMContext: path for document links.

    • CustomScrapedFileRegisterPatterns: list of paths for custom name patterns. Every path consists of a rank, a pattern and a path. Check the attached file sample for examples. Use an asterisk character to match any string (for example, *-test-*.txt will match any file that has “- test-” keyword preceded and succeeded by any string - aconex-test-regi.txt).

  • FileTimeStampFormat: timestamp format that will be used for delta file name.

  • FileNamePrefix: file name prefix for regi files, used for identification.

  • FileNameSuffixForDelta

    • Suffix: delta filename suffix.

    • Extension: delta extension. Represent the DeltaEndpoint response type extension to be saved to. If endpoint response is XML, then the extension will be xml. Same for any other response type.

AIMIngestion

AIMIngestion section is about ingestion configuration.

  • BaseUrl: represents the base url for ingestion api.

  • AssetId: represents the ID of the asset for which the upload is done.

  • ProcessingUnit: represents the processing units with the attached allowed extension type.

HttpSettings

HttpSettings section configures timeouts and retries. Most of them are hardcoded in the template, only the DMS timeout must be configured by user.

  • DmsTimeout: timeout used for DMS http calls (in minutes - minimum 7, maximum 30).

PipelineRunnerSettings

PipelineRunnerSettings is a section that configures the flow of the program. Most of the configurations are already hardcoded in the template.

  • DownloadFiles: boolean, switch for toggling on and off the files transfer. If set to FALSE, only delta file and document links are transferred.

Getting Aconex Client Credentials from Oracle

The Oracle Construction and Engineering Lobby (or "Lobby" for short), provides an OAuth 2.0 implementation for all Oracle Smart Construction Platform applications, including Aconex. This implementation is sometimes referred to as "Lobby OAuth".

Users authenticate with their Lobby account credentials and if they have multiple linked Aconex accounts, they will be required to select one account.

For more details on how Oracle OAuth 2.0 implementation works, see Smart Construction Platform OAuth.

Oracle Construction and Engineering Lobby currently supports four types of integrations, that are documented in detail in the link mentioned above. For integration using the Document Connector, the “User-Bound Integration” is supported. This integration has no user interaction and is bound to a specified Aconex user account.

Registering this integration is a manual process that needs to be carried out before configuring the Document Connector. The Aconex user needs to raise a support ticket with Oracle to get the client credentials. The section below outlines the key inputs that will be required for raising this ticket and how to get these values from Aconex. The Oracle support team usually responds within 2-4 working days with the client credentials. The Aconex Sample for the Document Connector outlines the relevant configuration changes required to setup the Document Connector to use this authentication mechanism.

Setting up your Oracle Construction and Engineering Account

The first step in configuring a User-Bound Integration is setting up your individual Oracle Construction and Engineering account. To do this, follow the steps provided below:

  1. Login to your Aconex account. You will be prompted to use a new way to sign in to Aconex, select “Skip This Time”.

    The Aconex sign in window with the Skip This Time button highlighted.

  2. After you have logged in, navigate to the Setup menu item. Select “Create Oracle Construction and Engineering account”.

    The Create Oracle Construction and Engineering account option highlighted in Aconex.

  3. Follow the instructions through the setup wizard and you will be able to configure this account.

  4. When you successfully setup and log back into Aconex, navigate to Setup. Select Account Details.

    User ID highlighted in the account details page in Aconex.

  5. Copy your User ID. This will be used later.

Retrieving your Organization Lobby ID

This step can only be performed by the Aconex organization administrator. The steps below are for the administrator to follow.

  1. Login to your Aconex account.

  2. Navigate to “https://constructionandengineering.oraclecloud.com/web/home/projects”.

  3. Click on the Navigation menu in the top left corner. Select Organizations.

    The navigation menu highlighted in Construction and Engineering.

    The organizations option highlighted in Construction and Engineering.

  4. Copy the Organization ID field. This will be used in the next step.

    Information Required to Register an Aconex Customer Integration

    You must provide the following information to raise the Oracle support ticket to get your client credentials, provided your Oracle Construction and Engineering account is ready and you have the Lobby Organization ID.

    • Lobby Organization ID(s) - Provide the “Organization ID” copied earlier.

    • Unique Name - For example - “AVEVA Document Connector Dev Connection”. Create a unique name based on your organization.

    • Description - For example - “Integration between AVEVA Document Connector and Aconex for Project X”.

    • Client Type - Keep this value as “User-Bound Integration”.

    • Aconex User ID - Provide the User ID copied above. Also provide your Aconex email ID for reference.

    • Aconex Instance - For example - “us1.aconex.com”.

    Unsupported characters

    The following non-printable characters are unsupported and removed from the file’s metadata:

    • Null character: \u0000

    • Control characters from \u0001 to \u0008

    • Vertical tab: \u000B

    • Form feed: \u000C

    • Control characters from \u000E to \u001F

    • Delete character: \u007F

    In This Topic
    TitleResults for “How to create a CRG?”Also Available in